Documented the loadForEnv() method #10626

javiereguiluz · 2018-10-31T16:28:10Z

dunglas · 2018-11-05T11:36:10Z

components/dotenv.rst

+
+.. versionadded:: 4.2
+    The ``Dotenv::loadForEnv()`` method was introduced in Symfony 4.2.
+
 You should never store a ``.env`` file in your code repository as it might


This sentence should be remove in favor of the paragraph you introduced, right?

dunglas · 2018-11-05T11:43:26Z

components/dotenv.rst

+the app on your local machine. The other two optional files (``.env`` +
+"environment name" + ``.local`` and ``.env`` + "environment name") work
+similarly, but they are specific to some environment.
+


May I suggest to add the following:

Suggested change

``DotEnv::loadForEnv()`` implements the exact same behavior than Ruby's `dotenv library`_ and `Create React App's .env support`_. These projects provide extensive documentation about environment variables handling, that is worth reading.

dunglas · 2018-11-05T11:43:27Z

components/dotenv.rst

@@ -112,3 +148,4 @@ Embed commands via ``$()`` (not supported on Windows):

 .. _Packagist: https://packagist.org/packages/symfony/dotenv
 .. _twelve-factor applications: http://www.12factor.net/
+.. _`app config recommendations`: https://12factor.net/config


Suggested change

.. _`app config recommendations`: https://12factor.net/config

.. _`app config recommendations`: https://12factor.net/config

.. _`dotenv library`: https://github.com/bkeepers/dotenv

.. _`Create React App's .env support`: https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#what-other-env-files-can-be-used

dunglas · 2018-11-05T11:46:08Z

components/dotenv.rst

+    $dotenv->loadForEnv('dev', __DIR__.'/.env');
+    // Looks for env vars in these files (and in this order):
+    //   .env.dev.local
+    //   .env.local


Will be loaded after .env.dev

Will be loaded after .env.dev

Hmm. Are you sure? I didn't check the code, but if it's true it's not respecting the same priorities as https://github.com/bkeepers/dotenv/blob/master/README.md#what-other-env-files-can-i-use, i.e:

.env.[env].local

.env.local

.env.[env]

.env

Also, what about using the same presentation as bkeepers/dotenv? (The table with complementary information)

But https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#what-other-env-files-can-be-used does load .env.local after .env.[env]...

IMHO, loading .env.local before .env.[env] makes more sense, as x.local should always allow override. Either you use .env.local to override for all environments, either you use .env.[env].local for a specific env. But .env and .env.[env] will only contains sensible defaults, so .env.[env] should not have precedence over .env.local.

dunglas · 2018-11-05T11:49:35Z

components/dotenv.rst

+    //   .env
+
+The ``.env`` file should be committed to the shared repository and contains the
+default env var values for the app. The optional ``.env.local`` file shouldn't


Suggested change

default env var values for the app. The optional ``.env.local`` file shouldn't

default env var values for the app. The ``.env`` file should contain development-only settings. It **must not** contain any settings used in production. They are placeholder values helping during the onboarding process. The optional ``.env.local`` file shouldn't

dunglas · 2018-11-05T11:57:00Z

components/dotenv.rst

+    //   .env.test.local
+    //   .env.test
+    //   .env
+


Suggested change

Similarly to ``DotEnv::load()``, ``DotEnv::loadForEnv()`` never overwrites existing environment variables, nor variables defined by files loaded previously. For instance, if the same variable is defined in both `.env` and `.env.test.local`, the value will be the one defined in `.env.test.local`, because this file is loaded first by ``DotEnv::loadForEnv()``.

I would add somewhere something similar to https://github.com/bkeepers/dotenv/blob/master/README.md#can-i-use-dotenv-in-production last paragraph:

please note that env vars that are general to all environments should be stored in .env. Then, environment specific env vars should be stored in .env.<that environment's name>.

i.e no need to repeat all env vars. Only the ones likely to be specific for the target env.

ogizanagi

Thanks a lot for working on this! ❤️

ogizanagi · 2018-11-05T13:23:51Z

components/dotenv.rst

+    $dotenv->loadForEnv('dev', __DIR__.'/.env');
+    // Looks for env vars in these files (and in this order):
+    //   .env.dev.local
+    //   .env.local


Will be loaded after .env.dev

Hmm. Are you sure? I didn't check the code, but if it's true it's not respecting the same priorities as https://github.com/bkeepers/dotenv/blob/master/README.md#what-other-env-files-can-i-use, i.e:

.env.[env].local

.env.local

.env.[env]

.env

Also, what about using the same presentation as bkeepers/dotenv? (The table with complementary information)

ogizanagi · 2018-11-05T13:27:04Z

components/dotenv.rst

+    //   .env.test.local
+    //   .env.test
+    //   .env
+


I would add somewhere something similar to https://github.com/bkeepers/dotenv/blob/master/README.md#can-i-use-dotenv-in-production last paragraph:

please note that env vars that are general to all environments should be stored in .env. Then, environment specific env vars should be stored in .env.<that environment's name>.

i.e no need to repeat all env vars. Only the ones likely to be specific for the target env.

weaverryan · 2018-11-09T18:27:40Z

See symfony/recipes#481

But, those changes I believe also apply to 3.4

nicolas-grekas · 2018-11-10T17:01:48Z

Should be updated to account for #29129
Technically, the method is new to 4.2
But practically, the described behavior (loading .env < .env.local < .env.$env < .env.$env.local) works for new projects starting with 3.4 yes

weaverryan · 2018-11-13T02:20:56Z

And I think there are / will be a few more recipe changes still? Once those finish, we can finish this up as quickly as possible

weaverryan · 2018-11-15T17:26:11Z

See #10680 - it does not replace this PR (at least not entirely) as in #10680 I don't describe the actual new loadForEnv() method (though I do describe its behavior, which, thanks to the recipe changes, is available to any Symfony project in any version).

nicolas-grekas · 2018-11-15T17:37:56Z

Note that the method changed to loadEnv() with different signature and behavior.

javiereguiluz · 2019-01-02T11:15:18Z

I'm closing this because the handling of .env files is still "a moving target" and too many things are still changing. Let's work on this again after things settle down. Thanks!

Documented the loadForEnv() method

bac4e47

javiereguiluz added Missing Documentation Dotenv labels Oct 31, 2018

javiereguiluz added this to the 4.2 milestone Oct 31, 2018

carsonbot added the Status: Needs Review label Oct 31, 2018

Improved the explanation

4dac1e2

dunglas reviewed Nov 5, 2018

View reviewed changes

ogizanagi reviewed Nov 5, 2018

View reviewed changes

ogizanagi mentioned this pull request Nov 7, 2018

[Dotenv] add loadEnv(), a smoother alternative to loadForEnv() symfony/symfony#29129

Merged

javiereguiluz closed this Jan 2, 2019


	``DotEnv::loadForEnv()`` implements the exact same behavior than Ruby's `dotenv library`_ and `Create React App's .env support`_. These projects provide extensive documentation about environment variables handling, that is worth reading.

	default env var values for the app. The optional ``.env.local`` file shouldn't
	default env var values for the app. The ``.env`` file should contain development-only settings. It must not contain any settings used in production. They are placeholder values helping during the onboarding process. The optional ``.env.local`` file shouldn't


	Similarly to ``DotEnv::load()``, ``DotEnv::loadForEnv()`` never overwrites existing environment variables, nor variables defined by files loaded previously. For instance, if the same variable is defined in both `.env` and `.env.test.local`, the value will be the one defined in `.env.test.local`, because this file is loaded first by ``DotEnv::loadForEnv()``.

Uh oh!

Documented the loadForEnv() method #10626

Documented the loadForEnv() method #10626

Uh oh!

Conversation

javiereguiluz commented Oct 31, 2018

Uh oh!

dunglas Nov 5, 2018

Choose a reason for hiding this comment

Uh oh!

dunglas Nov 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dunglas Nov 5, 2018

Choose a reason for hiding this comment

Uh oh!

dunglas Nov 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ogizanagi Nov 5, 2018

Choose a reason for hiding this comment

Uh oh!

ogizanagi Nov 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dunglas Nov 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dunglas Nov 5, 2018

Choose a reason for hiding this comment

Uh oh!

ogizanagi Nov 5, 2018

Choose a reason for hiding this comment

Uh oh!

ogizanagi left a comment

Choose a reason for hiding this comment

Uh oh!

ogizanagi Nov 5, 2018

Choose a reason for hiding this comment

Uh oh!

ogizanagi Nov 5, 2018

Choose a reason for hiding this comment

Uh oh!

weaverryan commented Nov 9, 2018

Uh oh!

nicolas-grekas commented Nov 10, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

weaverryan commented Nov 13, 2018

Uh oh!

weaverryan commented Nov 15, 2018

Uh oh!

nicolas-grekas commented Nov 15, 2018

Uh oh!

javiereguiluz commented Jan 2, 2019

Uh oh!

Uh oh!

dunglas Nov 5, 2018 •

edited

Loading

dunglas Nov 5, 2018 •

edited

Loading

ogizanagi Nov 5, 2018 •

edited

Loading

dunglas Nov 5, 2018 •

edited

Loading

nicolas-grekas commented Nov 10, 2018 •

edited

Loading